{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# hvPlot.image\n",
    "\n",
    "```{eval-rst}\n",
    ".. currentmodule:: hvplot\n",
    "\n",
    ".. automethod:: hvPlot.image\n",
    "```\n",
    "\n",
    "## Backend-specific styling options\n",
    "\n",
    "```{eval-rst}\n",
    ".. backend-styling-options:: image\n",
    "```\n",
    "\n",
    "## Examples\n",
    "\n",
    "### Basic image plot\n",
    "\n",
    "`colorbar` is True by default."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "import numpy as np\n",
    "import xarray as xr\n",
    "\n",
    "x = np.linspace(0, 10, 100)\n",
    "y = np.linspace(0, 5, 50)\n",
    "X, Y = np.meshgrid(x, y)\n",
    "data = np.exp(np.sin(X) * np.cos(Y) * 3)\n",
    "ds = xr.Dataset({\"value\": ([\"y\", \"x\"], data)}, coords={\"y\": y, \"x\": x})\n",
    "\n",
    "ds.hvplot.image()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Air temperature image grid\n",
    "\n",
    "Let's display an image from a real-world dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "\n",
    "ds = hvplot.sampledata.air_temperature(\"xarray\").sel(time=\"2014-02-25 12:00\")\n",
    "\n",
    "ds.hvplot.image(x=\"lon\", y=\"lat\", z=\"air\", cmap=\"viridis\", data_aspect=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use of `groupby`\n",
    "\n",
    "When the grid has more dimensions, like `time` in the example below, widgets are automatically created to explore further the dataset. This is equivalent to setting the [`groupby`](option-groupby) to the remaining dimension(s)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "\n",
    "ds = hvplot.sampledata.air_temperature(\"xarray\").isel(time=[0, 1])\n",
    "\n",
    "ds.hvplot.image(\n",
    "    x=\"lon\", y=\"lat\", z=\"air\", groupby=\"time\",\n",
    "    frame_width=400, data_aspect=1, dynamic=False,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use of `logz`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "import numpy as np\n",
    "import xarray as xr\n",
    "\n",
    "x = np.linspace(0, 10, 100)\n",
    "y = np.linspace(0, 5, 50)\n",
    "X, Y = np.meshgrid(x, y)\n",
    "data = np.exp(np.sin(X) * np.cos(Y) * 3) * 100\n",
    "ds = xr.Dataset({\"value\": ([\"y\", \"x\"], data)}, coords={\"y\": y, \"x\": x})\n",
    "\n",
    "ds.hvplot.image(logz=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(image-vs-quadmesh)=\n",
    "### Image vs. Quadmesh"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The constructor of the HoloViews [`Image`](https://holoviews.org/reference/elements/bokeh/Image.html) element, object returned by an `image` call, attempts to validate the input data by ensuring it is regularly sampled. In some cases, your data may be not be regularly sampled to a sufficiently high precision in which case you will see an exception recommending the use of the `Quadmesh` element instead. If you see this message and are sure that the `Image` element is appropriate, you can set the `rtol` value globally using `hv.config.image_rtol` in  to allow a higher deviation in sample spacing than the default of 10e-6. If not, use the `quadmesh` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "\n",
    "ds = hvplot.sampledata.air_temperature(\"xarray\").sel(time=\"2014-02-25 12:00\")\n",
    "# Emulate irregular grid\n",
    "ds.coords[\"lat\"] = ds.coords[\"lat\"]**2\n",
    "\n",
    "ds.hvplot.image(x=\"lon\", y=\"lat\", z=\"air\", cmap=\"blues\", width=400, height=400)"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
